#ifndef __APP_BUZZER_H__
#define __APP_BUZZER_H__

#include "app_config.h"


// 蜂鸣器状态枚举
typedef enum {
    APP_BUZZER_STATE_IDLE = 0,    // 空闲状态
    APP_BUZZER_STATE_PLAYING,     // 播放中
    APP_BUZZER_STATE_ERROR        // 错误状态
} app_buzzer_state_t;

// 蜂鸣器配置结构体
typedef struct {
    uint16_t default_freq;        // 默认频率
    uint8_t default_volume;      // 默认音量(0-100)
    uint16_t interrupt_period;    // 中断周期(ms)
} app_buzzer_config_t;

// 蜂鸣器应用层结构体
typedef struct {
    buzzer_t buzzer;              // 底层蜂鸣器句柄
    app_buzzer_state_t state;     // 应用层状态
    app_buzzer_config_t config;   // 配置参数
    uint8_t is_initialized;       // 初始化标志
} app_buzzer_t;

// 全局蜂鸣器实例
extern app_buzzer_t app_buzzer;

// ==================== 基础控制函数 ====================

/**
 * @brief 初始化应用层蜂鸣器
 * @return buzzer_err_e 错误码
 */
buzzer_err_e app_buzzer_init(void);

/**
 * @brief 反初始化蜂鸣器
 */
void app_buzzer_deinit(void);

/**
 * @brief 获取蜂鸣器状态
 * @return app_buzzer_state_t 当前状态
 */
app_buzzer_state_t app_buzzer_get_state(void);

/**
 * @brief 检查蜂鸣器是否正在播放
 * @return uint8_t 1-正在播放, 0-空闲
 */
uint8_t app_buzzer_is_playing(void);

// ==================== PWM控制函数 ====================

/**
 * @brief 设置PWM占空比
 * @param dc 占空比(0-100)
 */
void pwm_set_dc(uint32_t dc);

/**
 * @brief 设置PWM频率
 * @param freq 频率(Hz), 0表示关闭
 */
void pwm_set_freq(uint32_t freq);

// ==================== 基础播放函数 ====================

/**
 * @brief 立即播放指定频率
 * @param freq 频率(Hz)
 */
void app_buzzer_play_freq(uint16_t freq);

/**
 * @brief 停止播放
 */
void app_buzzer_stop(void);

/**
 * @brief 播放指定时长的音调
 * @param freq 频率(Hz)
 * @param duration 持续时间(ms)
 */
void app_buzzer_beep(uint16_t freq, uint16_t duration);

/**
 * @brief 播放循环音调
 * @param freq 频率(Hz)
 * @param period 周期(ms)
 * @param loop 是否循环
 */
void app_buzzer_beep_loop(uint16_t freq, uint16_t period, uint8_t loop);

// ==================== 预设提示音函数 ====================

/**
 * @brief 播放成功提示音
 */
void app_buzzer_play_success(void);

/**
 * @brief 播放错误提示音
 */
void app_buzzer_play_error(void);

/**
 * @brief 播放警告提示音
 */
void app_buzzer_play_warning(void);

/**
 * @brief 播放报警提示音
 */
void app_buzzer_play_alarm(void);

/**
 * @brief 播放按键提示音
 */
void app_buzzer_play_key_beep(void);

/**
 * @brief 播放开机提示音
 */
void app_buzzer_play_boot(void);

// ==================== 音乐播放函数 ====================

/**
 * @brief 播放马里奥主题曲
 */
void app_buzzer_play_mario_theme(void);

/**
 * @brief 播放地下世界音乐
 */
void app_buzzer_play_underworld(void);

/**
 * @brief 播放自定义音乐
 * @param melody 音符数组
 * @param timing 时长数组
 * @param length 数组长度
 */
void app_buzzer_play_melody(uint16_t *melody, uint16_t *timing, uint16_t length);

// ==================== 配置函数 ====================

/**
 * @brief 设置默认频率
 * @param freq 频率(Hz)
 */
void app_buzzer_set_default_freq(uint16_t freq);

/**
 * @brief 设置默认音量
 * @param volume 音量(0-100)
 */
void app_buzzer_set_default_volume(uint8_t volume);

/**
 * @brief 设置中断周期
 * @param period 周期(ms)
 */
void app_buzzer_set_interrupt_period(uint16_t period);

// ==================== 中断处理函数 ====================

/**
 * @brief 蜂鸣器中断处理函数(在定时器中断中调用)
 */
void app_buzzer_interrupt_handler(void);

// ==================== 回调函数 ====================

/**
 * @brief 播放完成回调函数(可重写)
 */
void app_buzzer_play_finished_callback(void);

#endif